Skip to main content
Version: DeepHub 2022 R2 - 2.2.3

Locating Rule Extension

A trackable can be associated with several location providers. For example, a trackable may have a GPS provider used for outdoor localization, as well as UWB and RFID location providers for indoor localization.

In practice this may result in multiple location updates at a time for each of the location providers. For example, the trackable may be located indoors and get a precise location via UWB while it gets a GPS location update with low accuracy at the same time. As a result, the trackable will get all location updates for each of its devices, and by default the most recent location update is marked as the most significant.

The trackable locating rule extension adds additional configuration options to a trackable in order to make fine-grained decisions about selecting the most significant location. Locating rules can be expressed via a simple domain specific language.

Details​

Each rule consists of two properties:

  • expression: A boolean expression consisting of AND connected expressions. The syntax is based on SQL.
  • priority: The priority assigned to the associated expression. It is a positive number, with 0 being the lowest priority.

A list of such rules can be assigned to a trackable or as default rules. The default rules are used for all trackables, which do not contain rules. If neither rules are present, the most recent location update has the highest priority. The default rules can be set with this API endpoint:
/trackables/rules/locating

Whenever a location update is processed all rules are evaluated for all locations associated with a trackable. Based on all expressions which evaluate to true, the largest priority is assigned to the respective location. The location with the highest priority is then assigned to the trackable as the most significant location. If no expression evaluates to true, a default priority of 0 is used.

A dedicated API for testing the expression syntax can be found at:
/validator/rules/locating

Available functions and properties​

timestamp_diff​

This function provides access to the "age" of a location update. It gives the time difference between the location's timestamp_generated and now in milliseconds.

accuracy​

This enables checks against the accuracy of the location update.

provider_id​

This enables checks against the provider id of the location update.

type​

This enables checks against the provider type of the location update. Available types are: uwb, gps, wifi, rfid, ibeacon, virtual, unknown

source​

This enables checks against the source of the location update.

floor​

This enables checks against the floor of the location update.

speed​

This enables checks against the speed of the location update.

Available operators​

The following operators are available for expressions: =, !=, <, <=, >, >=, and AND.

Example​

The following locating rules would be described in natural language as:

  • Use the precise UWB location if the location is not older than 10s,
  • otherwise switch back to GPS if the accuracy is better than 10m.
"locating_rules": [
  {
    "expression": "type = 'uwb' AND timestamp_diff < 10000",
    "priority": 10
  },
  {
    "expression": "type = 'gps' AND accuracy < 10000",
    "priority": 9
  }
]